org.globalplatform
Interface CVM

All Superinterfaces:

javacard.framework.Shareable

public interface CVM
extends javacard.framework.Shareable

This defines the interface of a Global Services Application implementing one or more Cardholder Verification Methods. This class offers basic Cardholder Verification Method services (e.g. CVM verification, CVM state interrogation) to any of the Applications present on the card, while some of the services (e.g. unblock CVM, change CVM value) are restricted to Applications with the privilege to change the CVM values. Prior to using this interface, an Application is required to obtain a handle to the CVM services. The CVM application shall expose the GlobalService interface object(s) through applet.getShareableInterfaceObject() according to this specification.

Since:

export file version 1.0

Field Summary

static short	CVM_FAILURE The CVM value comparison failed.
static short	CVM_SUCCESS The CVM value comparison was successful.
static byte	FORMAT_ASCII The CVM value is formatted as ASCII bytes.
static byte	FORMAT_BCD The CVM value is formatted as numerical digits, coded on a nibble (4 bits) and left justified.
static byte	FORMAT_HEX The CVM value is formatted as hexadecimal (binary) data.

Method Summary

boolean	blockState() This method sets the CVM state to BLOCKED.
byte	getTriesRemaining() This method returns the number of tries remaining for the CVM.
boolean	isActive() This method indicates whether the CVM is present and activated.
boolean	isBlocked() This method indicates whether the CVM is currently BLOCKED.
boolean	isSubmitted() This method indicates whether an attempt has been made to compare the CVM value.
boolean	isVerified() This method indicates whether a successful comparison of the CVM value has occurred (CVM state of VALIDATED).
boolean	resetAndUnblockState() This method resets the CVM state from BLOCKED to ACTIVE.
boolean	resetState() This method resets the CVM state to ACTIVE.
boolean	setTryLimit(byte bTryLimit) This method sets the maximum number of tries for the CVM.
boolean	update(byte[] baBuffer, short sOffset, byte bLength, byte bFormat) This method changes the CVM value.
short	verify(byte[] baBuffer, short sOffset, byte bLength, byte bFormat) This method compares the stored CVM value with the one passed as parameter.

Field Detail

CVM_SUCCESS

static final short CVM_SUCCESS

The CVM value comparison was successful.

See Also:

Constant Field Values

CVM_FAILURE

static final short CVM_FAILURE

The CVM value comparison failed.

See Also:

Constant Field Values

FORMAT_ASCII

static final byte FORMAT_ASCII

The CVM value is formatted as ASCII bytes.

Note:

• If the CVM value is stored in a format other than ASCII, it is the responsibility of the interface to convert to the expected format.

See Also:

Constant Field Values

FORMAT_BCD

static final byte FORMAT_BCD

The CVM value is formatted as numerical digits, coded on a nibble (4 bits) and left justified.

Note:

• If the CVM value is stored in a format other than BCD, it is the responsibility of the interface to convert to the expected format.
• If the length of the CVM value is odd, the right most nibble of the CVM value shall be high values ('F').

See Also:

Constant Field Values

FORMAT_HEX

static final byte FORMAT_HEX

The CVM value is formatted as hexadecimal (binary) data.

Note:

• If the CVM value is stored in a format other than HEX, it is the responsibility of the interface to convert to the expected format.

See Also:

Constant Field Values

Method Detail

isActive

boolean isActive()

This method indicates whether the CVM is present and activated. If active the CVM could be in any one of the following states: ACTIVE, INVALID_SUBMISSION, VALIDATED or BLOCKED.

Returns:

true if the CVM state is (at least) ACTIVE, false otherwise.

isSubmitted

boolean isSubmitted()

This method indicates whether an attempt has been made to compare the CVM value.

Note:

• This method does not differentiate whether the CVM value has been successfully verified or not, i.e. CVM states of VALIDATED or INVALID_SUBMISSION.

Returns:

true if the CVM state is (at least) SUBMITTED, false otherwise.

isVerified

boolean isVerified()

This method indicates whether a successful comparison of the CVM value has occurred (CVM state of VALIDATED).

Returns:

true if the CVM state is VALIDATED, false otherwise.

isBlocked

boolean isBlocked()

This method indicates whether the CVM is currently BLOCKED.

Returns:

true if the CVM state is BLOCKED, false otherwise.

getTriesRemaining

byte getTriesRemaining()

This method returns the number of tries remaining for the CVM. This indicates the number of times the CVM value can be incorrectly presented prior to the CVM reaching the state of BLOCKED.

Returns:

Tries remaining.

update

boolean update(byte[] baBuffer,
               short sOffset,
               byte bLength,
               byte bFormat)

This method changes the CVM value.

Notes:

• The CVM Application shall verify the CVM Management privilege using the GPRegistryEntry interface of the invoking applet;
• The invoking applet is responsible for specifying the format of the CVM value;
• The CVM Retry Counter is reset when changing the CVM value;
• The CVM state is reset to ACTIVE when changing the CVM value. When setting the CVM value before the CVM state is ACTIVE, the CVM state transitions to ACTIVE only if the Retry Limit is already set;
• Data presented always replaces the previous data regardless of its format or length. The CVM shall remember the format, length, and value of the CVM data. The CVM may (or may not) do editing checks on the data and reject the CVM update if the data fails the editing checks (e.g. reject data that is presented as BCD that is not numerical).

Parameters:

baBuffer - the source byte array containing the CVM value. This buffer must be global.

sOffset - the offset of the CVM value within source byte array.

bLength - the length of the CVM value.

bFormat - the format of the CVM value.

Returns:

true if the CVM value was changed, false otherwise.

resetState

boolean resetState()

This method resets the CVM state to ACTIVE.

Notes:

• The state of the CVM can only be set to ACTIVE from the states INVALID_SUBMISSION or VALIDATED.
• The state of the CVM cannot be set to ACTIVE from BLOCKED.

Returns:

true if the CVM state was reset, false otherwise.

blockState

boolean blockState()

This method sets the CVM state to BLOCKED.

Notes:

• The CVM application shall verify the CVM Management privilege using the GPRegistryEntry interface of the invoking applet.

Returns:

true if the CVM state was set to BLOCKED, false otherwise.

resetAndUnblockState

boolean resetAndUnblockState()

This method resets the CVM state from BLOCKED to ACTIVE.

Notes:

• The CVM Application shall verify the CVM Management privilege using the GPRegistryEntry interface of the invoking applet;
• The CVM try counter is reset when unblocking the CVM.

Returns:

true if the CVM state was reset to ACTIVE, false otherwise.

setTryLimit

boolean setTryLimit(byte bTryLimit)

This method sets the maximum number of tries for the CVM.

Notes:

• The CVM Application shall verify the CVM Management privilege using the GPRegistryEntry interface of the invoking applet;
• The CVM try counter is reset when setting the maximum number of tries;
• The CVM state is reset to ACTIVE when changing the maximum number of tries. When setting the maximum number of tries before the CVM state is ACTIVE, the CVM state transitions to ACTIVE only if the CVM value is already set.

Parameters:

bTryLimit - the maximum number of tries for the CVM.

Returns:

true if the maximum number of tries was set, false otherwise.

verify

short verify(byte[] baBuffer,
             short sOffset,
             byte bLength,
             byte bFormat)

This method compares the stored CVM value with the one passed as parameter.

Notes:

• If the value passed as parameter is not in the same format as the CVM value, the value passed as parameter must be converted prior to comparing.
• If HEX format is presented for CVM verification and ASCII or BCD format was used for updating the CVM value, the comparison fails;
• If HEX format is presented for CVM verification and HEX format was used for updating the CVM value, the comparison succeeds when the length and the data value match exactly;
• If BCD or ASCII format is presented for CVM verification and HEX format was used for updating the CVM value, the comparison fails;
• If ASCII format is presented for CVM verification and BCD format was used for updating the CVM value, the comparison fails if the ASCII characters presented for verification are not all numerical (zero to nine). If all the ASCII characters are numerical, format conversion occurs and the comparison succeeds when the length and the data value match exactly;
• If BCD format is presented for CVM verification and ASCII format was used for updating the CVM value, the comparison fails if the CVM value contains non-numerical ASCII characters. If the CVM value contains only numerical ASCII characters, format conversion occurs and the comparison succeeds when the length and the data value match exactly;
• If the comparison is successful, the try counter must be reset and the CVM state must be set to VALIDATED.
• If the comparison is unsuccessful, the try counter must be updated and the CVM state must be set to INVALID_SUBMISSION.
• The Retry Counter object and the CVM states VALIDATED and INVALID_SUBMISSION shall not conform to a transaction in progress, i.e. they shall not revert to a previous value if a transaction in progress is aborted;
• If the maximum number of tries has been reached, the CVM state must be set to BLOCKED.

Parameters:

baBuffer - the source byte array containing the submitted CVM value. This buffer must be global.

sOffset - the offset of the submitted CVM value within source byte array.

bLength - the length of the submitted CVM value.

bFormat - the format of the submitted CVM value.

Returns:

value indicating whether the comparison was successful or not. Values other than CVM_SUCCESS (0) or CVM_FAILURE (-1) are Reserved for Future Use.